# 远程访问

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

**RDP**（Remote Desktop Protocol，远程桌面协议）是一种图形化远程桌面连接方式。Windows 主机可使用系统自带的"远程桌面连接"工具访问 Quectel Pi 开发板（M1/L1）Debian 桌面，并在远端查看或控制图形界面。

Quectel Pi M1 主要使用 **GNOME** 桌面环境，已集成 GNOME 远程桌面功能，无需额外安装 VNC、Xvfb 或 x11vnc 等软件；Quectel Pi L1 当前使用 **Weston** 图形环境，可通过 Weston 自带的 **RDP backend** 提供远程桌面服务。

```{note}
M1 使用 RDP 远程桌面连接时，需保持图形桌面会话处于登录状态。L1 的 RDP 建议使用 Weston `rdp-backend.so`。
```

# 准备工作

1. **确认设备环境：**  
    - Quectel Pi M1 / L1 已启动 Debian 系统；  
    - Windows 主机和开发板处于同一网段或同一局域网内的可达网络；  
    - Windows 主机已安装或启用"远程桌面连接"工具。

2. **建议通过串口进入开发板。** 串口连接的详细说明可参考 debug_uart.md。M1 默认登录用户请按照引导使用自己所创建的账号密码；L1 默认使用 `root` 用户登录，且无密码。若本地调试环境已可用，也可以通过 ADB 进入系统（L1）。

3. **获取设备 IP 地址。** 在开发板端执行：

```bash
hostname -I
```

记录当前网络下的 IP 地址，后续 Windows 远程桌面连接时需要使用该地址。

> 💡 注：Windows 主机与开发板需要处于同一网段或同一局域网内，且两端网络可互通，否则即使板端已启动 RDP 服务，也无法正常连接。

若计划使用普通用户 `q` 启动 RDP 服务（L1），可先创建用户并设置密码：

```bash
adduser --disabled-password --gecos "" q
echo 'q:q' | chpasswd
```

若系统中已经存在可用普通用户，也可直接复用现有用户，无需重复创建。

# M1：GNOME 远程桌面

## 软件安装

Quectel Pi M1 Debian 系统的 GNOME 桌面环境已集成远程桌面相关功能。通常无需额外安装 VNC、Xvfb 或 x11vnc 等软件。

可在终端中执行以下命令确认远程桌面管理工具是否存在：

```bash
which grdctl
```

若命令返回 `/bin/grdctl`，说明系统已包含 GNOME 远程桌面管理工具。

## 软件配置

1. **进入远程桌面设置界面。** 通过 Quectel Pi M1 图形界面依次进入：设置 > 系统 > 远程桌面

2. **打开远程桌面功能。** 在远程桌面设置界面中，可根据实际使用需求打开以下开关：  
    - **桌面共享**：允许其他设备通过 RDP 协议查看当前桌面。  
    - **远程控制**：允许远程连接端控制鼠标和键盘。

```{image} images/image_GuDzbXkcmooDPdx7JxtcdGbGnme.webp
:width: 1280px
:height: 800px
```

3. **查看连接信息。** 在远程桌面设置界面中，可查看以下信息：主机名（用于局域网内识别设备）、端口（默认 RDP 端口为 `3389`）、用户名、密码。若需要修改登录密码，可点击密码区域右侧的编辑按钮，并按照界面提示重新设置。

## 保持远程桌面登录密码

若仅在系统设置的远程桌面页面中修改登录密码，设备重启或重新登录后可能需要再次设置。若希望远程桌面登录密码保持可用，可通过 **密码与密钥** 工具修改 `Login` 钥匙环密码。

1. 在应用列表中打开 **实用工具**，点击 **密码和密钥**。

```{image} images/image_P0hUbdoUTo7mnMxugwdclFpRnNh.webp
:width: 1280px
:height: 800px
```

2. 在 **密码** 分类中选择 `Login`，右键点击远程桌面凭据，选择 **更改密码**。

```{image} images/image_WNPfbb63NoKycUxnMoDcUvMinSg.webp
:width: 1280px
:height: 800px
```

3. 输入旧密码。旧密码为前面在远程桌面设置中配置的远程登录密码，例如本文测试环境中设置的 `q`。

```{image} images/image_LLHebvic4o80hJx2kTecHlUknQg.webp
:width: 1280px
:height: 800px
```

4. 设置新的 `Login` 钥匙环密码。若希望系统登录后自动读取远程桌面凭据，可将新密码留空并点击 **Continue**。

5. 若新密码留空，系统会提示密码将以未加密方式保存，确认后点击 **Continue**。

```{image} images/image_XW5KbnPh5o2d6bxQfdHcAW1inbb.webp
:width: 1280px
:height: 800px
```

```{note}
将 `Login` 钥匙环密码设置为空会降低凭据安全性，仅建议在开发调试环境中使用。若设备用于生产环境或多人共用环境，建议设置非空密码，并按需手动解锁钥匙环。
```

# 软件启动

在图形界面中打开 **桌面共享** 后，GNOME 远程桌面服务会自动启用。

也可以在终端中使用以下命令查看当前状态：

```bash
grdctl status --show-credentials
```

正常情况下，可看到 RDP 相关状态、端口、用户名以及远程控制模式等信息。

若需要通过命令行开启 RDP 后端，可执行：

```bash
grdctl rdp enable
```

若需要允许远程端控制鼠标和键盘，可执行：

```bash
grdctl rdp disable-view-only
```

若只允许远程端查看桌面，不允许控制鼠标和键盘，可执行：

```bash
grdctl rdp enable-view-only
```

```{note}
实际使用中建议优先通过图形界面完成配置，避免命令行配置与界面显示状态不一致。
```

# L1：Weston RDP Backend

## 软件安装

检查 Weston 是否支持 RDP backend：

```bash
env LD_LIBRARY_PATH=/opt/qcom/lib:/lib weston --help | grep -i rdp
find /usr/lib* -name 'rdp-backend.so' 2>/dev/null
```

若能看到 `rdp-backend.so`，说明当前系统已包含 Weston RDP backend。

```{note}
Quectel Pi L1 当前镜像中的 `weston` 依赖 `/opt/qcom/lib` 下的运行库。若直接执行 `weston` 提示 `libweston-10.so.0: cannot open shared object file`，需在命令前补充 `LD_LIBRARY_PATH=/opt/qcom/lib:/lib`。
```

# 软件配置

### 配置RDP证书

Weston RDP backend 需要 TLS 证书和私钥。可根据启动用户选择证书保存位置。

若使用 `root` 启动 RDP 服务，可生成证书到 `/etc/weston`：

```bash
mkdir -p /etc/weston
openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout /etc/weston/rdp.key \
  -out /etc/weston/rdp.crt \
  -days 365 \
  -subj "/CN=quectel-pi-l1"
chmod 600 /etc/weston/rdp.key
chmod 644 /etc/weston/rdp.crt
```

若使用普通用户 `q` 启动 RDP 服务，可生成证书到 `/home/q`：

```bash
mkdir -p /home/q
openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout /home/q/weston-rdp.key \
  -out /home/q/weston-rdp.crt \
  -days 365 \
  -subj "/CN=quectel-pi-l1"
chown q:q /home/q/weston-rdp.key /home/q/weston-rdp.crt
chmod 600 /home/q/weston-rdp.key
chmod 644 /home/q/weston-rdp.crt
```

若系统中已经存在可用证书，也可直接复用现有证书路径。

# 软件启动

## 推荐方式：共享当前物理屏幕

若希望 RDP 连接后看到的是本地 MIPI/HDMI 屏幕上的同一个 Weston 画面，应启用 Weston 的 `screen-share.so` 模块。该方式会由本地 Weston 自动拉起 RDP 共享进程，适合远程查看和操作当前物理屏幕。

可执行以下命令修改 `/etc/xdg/weston/weston.ini`：

```bash
python3 - <<'PY'
from pathlib import Path

p = Path("/etc/xdg/weston/weston.ini")
s = p.read_text()

s = s.replace("#modules=screen-share.so", "modules=screen-share.so")
s = s.replace("--rdp-tls-cert=/data/misc/display/tls.crt", "--rdp-tls-cert=/etc/weston/rdp.crt")
s = s.replace("--rdp-tls-key=/data/misc/display/tls.key", "--rdp-tls-key=/etc/weston/rdp.key")
s = s.replace("start-on-startup=false", "start-on-startup=true")

p.write_text(s)
PY
```

修改后重启系统：

```bash
reboot
```

系统重启后检查 Weston 和 RDP 共享进程：

```bash
ps -ef | grep weston
netstat -ltnp | grep 3389
cat /tmp/weston-rdp-share.log
```

若能看到类似以下进程，表示本地 Weston 已自动启动 RDP 共享：

```
weston --idle-time=0 --log=/tmp/weston.log --config=/etc/xdg/weston/weston.ini --tty=1
weston --backend=rdp-backend.so --no-config --shell=fullscreen-shell.so --no-clients-resize --address=0.0.0.0 --rdp-tls-cert=/etc/weston/rdp.crt --rdp-tls-key=/etc/weston/rdp.key --log=/tmp/weston-rdp-share.log
```

此时 Windows 主机可直接使用远程桌面连接开发板的 IP 地址。该方式共享的是当前物理屏幕画面，不需要再手动执行 `weston --backend=rdp-backend.so`。

```{note}
`screen-share` 方式依赖本地 Weston 配置中的 `[screen-share]` 段。若系统中证书路径不同，请将命令中的 `/etc/weston/rdp.crt` 和 `/etc/weston/rdp.key` 替换为实际路径。
```

## 临时启动RDP服务

Weston RDP backend 也可使用 `root` 或普通用户 `q` 临时启动一个独立的 RDP 桌面：

- `root` 启动：适合 L1 初始环境、串口 root 登录后的快速验证。

- `q` 启动：适合已创建普通用户后的日常使用。

该方式会创建一个新的 Weston RDP 桌面，不会镜像本地 MIPI/HDMI 物理屏幕。若需要远程共享当前物理屏幕，请优先使用上一节的 `screen-share` 方式。

同一时间只启动一个 Weston RDP 实例即可，不要同时执行多个启动命令，否则会抢占 `3389` 端口。

### 使用root启动

前台启动：

```bash
env LD_LIBRARY_PATH=/opt/qcom/lib:/lib weston --backend=rdp-backend.so \
  --socket=wayland-rdp-root \
  --idle-time=0 \
  --rdp-tls-cert=/etc/weston/rdp.crt \
  --rdp-tls-key=/etc/weston/rdp.key \
  --width=1280 \
  --height=800
```

后台启动：

```bash
nohup env LD_LIBRARY_PATH=/opt/qcom/lib:/lib weston --backend=rdp-backend.so \
  --socket=wayland-rdp-root \
  --idle-time=0 \
  --rdp-tls-cert=/etc/weston/rdp.crt \
  --rdp-tls-key=/etc/weston/rdp.key \
  --width=1280 \
  --height=800 \
  >/tmp/weston-rdp.log 2>&1 &
```

### 使用普通用户启动

启动前准备运行目录。若当前已登录为 `q` 用户，可跳过 `chown` 命令；若当前为 `root` 用户，可完整执行以下命令：

```bash
mkdir -p /run/user/1007
chown q:q /run/user/1007
chmod 700 /run/user/1007
```

以下命令需在 `q` 用户下执行。若当前提示符已经是 `q@...`，直接执行即可，不需要再添加 `runuser -u q --`。

`runuser -u q --` 只在当前登录用户是 `root` 时使用，用于从 `root` shell 临时切换到 `q` 用户身份执行后面的命令。若当前已经登录为 `q` 用户，再添加 `runuser -u q --` 可能会因为环境中没有该命令而执行失败。

前台启动：

```bash
env -i \
  HOME=/home/q \
  USER=q \
  LOGNAME=q \
  SHELL=/bin/bash \
  PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin \
  XDG_RUNTIME_DIR=/run/user/1007 \
  LD_LIBRARY_PATH=/opt/qcom/lib:/lib \
  weston --backend=rdp-backend.so \
  --socket=wayland-rdp \
  --idle-time=0 \
  --rdp-tls-cert=/home/q/weston-rdp.crt \
  --rdp-tls-key=/home/q/weston-rdp.key \
  --width=1280 \
  --height=800
```

后台启动：

```bash
nohup env -i \
  HOME=/home/q \
  USER=q \
  LOGNAME=q \
  SHELL=/bin/bash \
  PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin \
  XDG_RUNTIME_DIR=/run/user/1007 \
  LD_LIBRARY_PATH=/opt/qcom/lib:/lib \
  weston --backend=rdp-backend.so \
  --socket=wayland-rdp \
  --idle-time=0 \
  --rdp-tls-cert=/home/q/weston-rdp.crt \
  --rdp-tls-key=/home/q/weston-rdp.key \
  --width=1280 \
  --height=800 \
  >/tmp/weston-rdp.log 2>&1 &
```

若当前是在 `root` 用户下执行，也可以在上述启动命令的 `env -i` 前增加 `runuser -u q --`，切换到 `q` 用户启动 RDP 服务。例如：

```bash
runuser -u q -- env -i \
  HOME=/home/q \
  USER=q \
  LOGNAME=q \
  SHELL=/bin/bash \
  PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin \
  XDG_RUNTIME_DIR=/run/user/1007 \
  LD_LIBRARY_PATH=/opt/qcom/lib:/lib \
  weston --backend=rdp-backend.so \
  --socket=wayland-rdp \
  --idle-time=0 \
  --rdp-tls-cert=/home/q/weston-rdp.crt \
  --rdp-tls-key=/home/q/weston-rdp.key \
  --width=1280 \
  --height=800
```

检查 RDP 端口监听：

```bash
netstat -ltnp | grep 3389
```

若看到类似输出，表示 RDP 服务已启动：

```
tcp        0      0 0.0.0.0:3389            0.0.0.0:*               LISTEN      <PID>/weston
```

### 停止RDP服务

若需要停止临时启动的 Weston RDP 服务，可执行：

```bash
pkill -f 'weston.*rdp-backend'
```

# 远程桌面连接

1. 在 Windows 主机中打开"远程桌面连接"。

2. 在"计算机"输入框中填写开发板的 IP 地址，例如 `10.66.84.106`。如需手动指定端口，可填写 `10.66.84.106:3389`。

```{image} images/image_DXnmbWHiUoPDPbx6m9Rcp99FnKh.webp
:width: 475px
:height: 286px
```

1. 点击"连接"，并根据提示输入远程桌面设置界面中显示的用户名和密码。若 Windows 安全中心提示输入凭据，可点击 **更多选项**，选择 **使用其他帐户**，然后输入远程桌面设置界面中配置的用户名和密码。

```{image} images/image_KKpkb0vBioaRVwxNIfPcP1ebnZd.webp
:width: 456px
:height: 580px
```

1. 连接成功后，即可在 Windows 主机中查看并操作 Debian 桌面。L1 连接成功后可远程查看并操作 Weston RDP 桌面。

```{image} images/image_DxSGbI33YoDhiyxyx7Sc8tFUn7d.webp
:width: 1280px
:height: 823px
```

```{image} images/image_JWNXb8tNHohz0xxMSffcJlTTnDh.webp
:width: 963px
:height: 459px
```

# 疑难解答

| **问题现象** | **可能原因** | **处理方法** |
| --- | --- | --- |
| `weston --help \| grep -i rdp` 无输出（L1） | Weston 未编译或未安装 RDP backend | 检查系统是否包含 `/usr/lib/libweston-*/rdp-backend.so` |
| `weston --help` 或启动 RDP 时提示 `libweston-10.so.0: cannot open shared object file`（L1） | 未设置 Weston 运行所需动态库路径 | 在执行 Weston 相关命令前增加 `LD_LIBRARY_PATH=/opt/qcom/lib:/lib` |
| 启动提示证书或私钥错误（L1） | 证书路径错误、文件不存在或私钥权限不正确 | 确认 `--rdp-tls-cert` 和 `--rdp-tls-key` 指向有效文件 |
| `netstat -ltnp \| grep 3389` 无输出（L1） | Weston RDP backend 未成功启动 | 查看 `/tmp/weston-rdp.log` 中的错误信息 |
| Windows 远程桌面无法连接（L1） | 没有可达 IP、3389 未监听或网络不通 | 在 L1 执行 `hostname -I`、`netstat -ltnp \| grep 3389`，并确认 Windows 与 L1 网络互通 |
| 连接时提示证书不受信任（L1） | 使用的是本机自签证书 | 确认 IP 无误后继续连接，或替换为受信任证书 |
| Windows 远程桌面无法连接（M1） | Windows 主机和 M1 不在同一局域网 | 确认两端网络连接，重新获取 M1 的 IP 地址 |
| Windows 远程桌面无法连接（M1） | IP 地址或端口填写错误 | 在 M1 上执行 `hostname -I` 确认 IP，端口使用默认 `3389` |
| Windows 远程桌面无法连接（M1） | **桌面共享** 未开启 | 进入 `设置 > 系统 > 远程桌面`，打开 **桌面共享** |
| 只能查看桌面，无法控制鼠标和键盘（M1） | **远程控制** 未开启，或当前为只读模式 | 打开 **远程控制**，或执行 `grdctl rdp disable-view-only` |
| 登录提示用户名或密码错误（M1） | 输入的凭据与远程桌面设置中显示的不一致 | 使用远程桌面设置界面中显示的用户名和密码，必要时重新生成或手动修改密码 |
| 重启或重新登录后远程桌面密码失效（M1） | `Login` 钥匙环未保持远程桌面凭据 | 按照"保持远程桌面登录密码"章节修改 `Login` 钥匙环密码 |
| 连接后画面异常或无法刷新（M1） | 图形桌面会话状态异常 | 确认 M1 已登录图形桌面，断开后重新连接 |
| 网络切换后无法连接（L1/M1） | 设备 IP 地址发生变化 | 重新执行 `hostname -I` 获取当前 IP 地址，并在 Windows 远程桌面中更新连接地址 |